PBReadAsync

PBReadAsync
Header:	Devices.h		Carbon status:	Supported

Reads any number of bytes from an open file.

OSErr PBReadAsync (
    ParmBlkPtr paramBlock
);

Parameter descriptions

paramBlock: A pointer to a basic File Manager parameter block.

function result: A result code.

DISCUSSION

The relevant fields of the parameter block are:

ioCompletion

On input, a pointer to a completion routine.
ioResult

On output, the result code of the function.
ioRefNum

On input, a file reference number for an open file to be read.
ioBuffer

On input, a pointer to a data buffer into which the bytes are read.
ioReqCount

On input, the number of bytes requested.
ioActCount

On output, the number of bytes actually read.
ioPosMode

On input, the positioning mode.
ioPosOffset

On input, the positioning offset. On output, the new position of the mark.

This function attempts to read ioReqCount bytes from the open file whose access path is specified in the ioRefNum field and transfer them to the data buffer pointed to by the ioBuffer field. The position of the mark is specified by ioPosMode and ioPosOffset. If your application tries to read past the logical end-of-file, PBReadAsync reads the data, moves the mark to the end-of-file, and returns eofErr as its function result. Otherwise, PBReadAsync moves the file mark to the byte following the last byte read and returns noErr.

You can specify that PBRead read the file data 1 byte at a time until the requested number of bytes have been read or until the end-of-file is reached. To do so, set bit 7 of the ioPosMode field. Similarly, you can specify that PBReadAsync should stop reading data when it reaches an application-defined newline character. To do so, place the ASCII code of that character into the high-order byte of the ioPosMode field; you must also set bit 7 of that field to enable newline mode.

When reading data in newline mode, PBReadAsync returns the newline character as part of the data read and sets ioActCount to the actual number of bytes placed into the buffer (which includes the newline character).

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.